<html>
<head>
<link href="../style/style.css" rel="stylesheet" type="text/css">
</head>
<body>
<p class="heading">
Widget module (last update 30/06/02)
</p>
<p class="subheading">
Description:
</p>
<p>
The widgetManager object provides a means to create and manipulate window objects. This module also includes the constructors
for cascading menus and statusbars which can be attached to windows. The Menubars can also be attached to the page as floating
items! The windows can be totally reskinned very easily, and the behaviour of the gui elements can be altered by the use of a
config file.
</p>
<p>
Please be aware that this module is for DOM2 browsers only. This is currently Internet Explorer 5/6, Netscape 6 and Mozilla.
As always, Opera is not supported (and never will be) due to its substandard Javascript/DOM implementation, but hopefully
Konqueror will soon be fully supported.
</p>
<p class="subheading">
To use:
</p>
<p class="jcode">
&lt;script language="Javascript" src="gamelib_widgets.js"&gt;&lt;/script&gt;
</p>
<p>
Unlike the rest of Gamelib, you do not need the gamelib_core module to use this module. It's totally self contained. You
also don't need the gamelib_mouse module unless you need mouse events for other elements like sprites and layers. The
WidgetManager also uses a separate config file called "<span class="strong">setup.html</span>" that it uses to set up numerous switches and values
that control its look and feel, as well as a couple of directories that hold the images for window decorations and menu
icons. The directory that holds these must be passed to the WidgetManager when it is initialised as follows:
</p>

<p class="jcode">
	InitWidgetManager('style/0','Init2()');
</p>
<p>
As you can see, we use the convenience function "InitWidgetManager" to handle the initialisation. It creates an instance
of "WidgetManager" called "widgetManager" (notice the capitalisation). It then loads in the setup.html file from the
directory passed as the first parameter (here it's "style/0" - no trailing slash). Finally it calls the function passed
to it as the second parameter ("Init2()" here). Be aware that it takes a few seconds to load in the setup.html file, so
you cannot use the widgetManager immediately after this statement. In this case, you would start the script that uses
widgetManager from the function "Init2()".
</p>
<p>
You then create a window (called "myWindow" in this example):
</p>
<p class="jcode">
var myWindow=widgetManager.createWindow(500,400,"A Test!",null,null,"test.html",200,100);
</p>
<p>
The above creates a Gl_Window object. The 8 values passed to the Gl_Window creation
function are as follows:
</p>
<p>
(1) width of window<br />
(2) height of window<br />
(3) Text for the title bar<br />
(4) X position (optional)<br />
(5) Y position (optional)<br />
(6) Page to load into window as it's created (optional)<br />
(7) Zoom X position. This is the X position from which the "Zoom" animation will start. (optional)<br />
(8) Zoom Y position. This is the Y position from which the "Zoom" animation will start. (optional)<br />
</p>

<p>
Now we have a window, we can add a menuBar object to it if we wish (see
<a href="widgetManager/gl_menubardoc.html">menuBar docs</a> for an example
of creating a menuBar object):
</p>

<p class="jcode">
myWindow.addMenuBar(myMenuBar);
</p>

<p>
If we wish, we can also add a status bar!
</p>

<p class="jcode">
myWindow.addStatusBar('Hi there!');
</p>

<p>
A couple of last points: The directory given when the widgetManager is initialised must contain the
<span class="strong">setup.html</span> file and 2 subdirectories. One subdirectory is called
<span class="strong">window_decorations</span>, and the other is called <span class="strong">menu_icons</span>.
</p>
<p>
The images in window_decorations have fixed names, and are used to construct the Gl_Window objects. There is an
example in the <a href="http://www.javascript-games.org/gamelib/gamelib.zip">gamelib.zip</a> file. The icons
for menu items go into the menu_icons subdirectory. These can be called anything you like, but
should be gif files, not jpegs! Please read through the setup.html file, it's very well documented, and must be
edited if you intend to create new skins, or if you wish to alter the behaviour and style of the Widget objects!
</p>

<p class="subheading">
List of Objects managed by WidgetManager
</p>

<p>
<a href="widgetManager/gl_windowdoc.html">Gl_Window</a><br />
<a href="widgetManager/gl_menubardoc.html">Gl_MenuBar</a><br />

</p>

<p class="subheading">
List of public methods for WidgetManager
</p>

<p>
<a href="#addEvent">addEvent</a><br>
<a href="#createWindow">createWindow</a><br>
<a href="#destroyWindow">destroyWindow</a><br>
<a href="#doWindowPrint">doWindowPrint</a><br>
<a href="#doWindowSearch">doWindowSearch</a><br>
<a href="#forwardResizeEvents">forwardResizeEvents</a><br>
</p>

<p class="subheading">
List of public properties for WidgetManager
</p>

<p>
<a href="#activeWindowIX">activeWindowIX</a><br />
<a href="#browserHeight">browserHeight</a><br />
<a href="#browserWidth">browserWidth</a><br />
<a href="#windowsOnScreen">windowsOnScreen</a><br />
</p>

<p class="subheading">
Descriptions of public methods for WidgetManager
</p>

<table>
<tr>
<th>Method</th>
<th NOWRAP>Parameters</th>
<th>Description</th>
</tr>

<tr>
<a name="addEvent"></a>
<td>addEvent</td>
<td>DOM object, String, Function Reference, Boolean</td>
<td>
A generic method for adding event listeners to DOM objects. This includes a fallback
for the Mac version of Internet Explorer, which doesn't actually have a proper method
for doing this. The first parameter is a reference to a DOM object, next is a string
representing the type of event to listen for. So, for a mouseover event, this would
be "mouseover" (no "on" prefix). The third parameter is a reference to the function
that will handle the event. The last parameter should be true if the event should not
bubble to the next listener (if there is one for this event).
</td>
</tr>

<tr>
<a name="createWindow"></a>
<td>createWindow</td>
<td>Numeric, Numeric, String, Numeric, Numeric, String, Numeric, Numeric</td>
<td>
The WidgetManager should always be used to create and destroy Gl_Window objects, as it
needs to manage the desktop and all windows in use upon the desktop. Use this method to
create a new Gl_Window. There is a maximum of 8 arguments for this method. Only the first
3 are required, all others are optional. The list of arguments is given below:
<ul>
 <li>Width of window.</li>
 <li>Height of window.</li>
 <li>Title text.</li>
 <li>Initial X position.</li>
 <li>Initial Y position.</li>
 <li>URL of page to load as window is created.</li>
 <li>X position that window should "zoom" out from.</li>
 <li>Y position that window should "zoom" out from.</li>
</ul>
</td>
</tr>

<tr>
<a name="destroyWindow"></a>
<td>destroyWindow</td>
<td>Numeric</td>
<td>
This will destroy a Gl_Window. The parameter should be the index of the window in the
widgetManager's windows[] array. If no parameter is used then current active window
will be destroyed. All Widgets have destroy() methods which cascade down, so when a 
window is destroyed all its child objects, including statusBar and menuBar will also
be destroyed. You should never call a Gl_Window's destroy method directly.
</td>
</tr>

<tr>
<a name="doWindowPrint"></a>
<td>doWindowPrint</td>
<td>none</td>
<td>
With MS Windows with Explorer, this will send the contents of the current active window
to the printer. With other browser/Operating systems it will pop up a new window containing
the contents of the active window ready for printing.
</td>
</tr>

<tr>
<a name="doWindowSearch"></a>
<td>doWindowSearch</td>
<td>none</td>
<td>
This will pop up a search dialog box. Once filled out and the submit button is pressed a
search will be perfomed on the contents of the active window. Any matches will be highlighted
in the window itself.
</td>
</tr>

<tr>
<a name="forwardResizeEvents"></a>
<td>forwardResizeEvents</td>
<td>String</td>
<td>
When the widgetManager is initialised, it automatically traps window resize events for
internal use. If you need another function called whenever a resize event occurs, this
method can be used. The parameter passed is a string containing the function to be called.
</td>
</tr>

</table>


<p class="subheading">
Descriptions of public properties for WidgetManager
</p>

<table>

<tr>
<th>Property</th>
<th NOWRAP>Data Type</th>
<th NOWRAP>Read/Write</th>
<th>Description</th>
</tr>

<tr>
<a name="activeWindowIX"></a>
<td>activeWindowIX</td>
<td>Numeric</td>
<td>R</td>
<td>
The index of the current active window. This is the window's position in the widgetManager's
windows[] array.
</td>
</tr>

<tr>
<a name="browserHeight"></a>
<td>browserHeight</td>
<td>Numeric</td>
<td>R</td>
<td>
Height of the browser window.
</td>
</tr>

<tr>
<a name="browserWidth"></a>
<td>browserWidth</td>
<td>Numeric</td>
<td>R</td>
<td>
Width of the browser window.
</td>
</tr>

<tr>
<a name="windowsOnScreen"></a>
<td>windowsOnScreen</td>
<td>Numeric</td>
<td>R</td>
<td>
Number of windows currently on screen. This includes shaded windows.
</td>
</tr>

</table>

</body>
</html>